<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>SympyCore User's Guide</title>
<meta name="authors" content="Pearu Peterson  Fredrik Johansson" />
<style type="text/css">

/*
:Author: Pearu Peterson
:Contact: pearu.peterson AT gmail DOT com
:Copyright: This stylesheet has been placed in the public domain.

Stylesheet for use with Docutils.
*/

@import url(html4css1.css);

/* Your customizations go here.  For example: */

body {
    margin:0px;
    padding:25px;
    background-color: #ccc;
    font-size: 13px; font-family: arial, sans-serif;
    line-height:1.5em;
}

div.document {
    max-width: 700px;
    color: #000;
    background-color: #fff;
    padding:25px;
    border:5px solid #ddd;
}

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

pre, tt {
  font-family: consolas, lucida console, courier new, monospace;
  color: #000080 ;
}

pre.literal-block, pre.doctest-block {
  line-height:1.3em;
  border-top:1px solid #ccc;
  border-bottom:1px solid #ccc;
  background-color:#f0f0f0;
  color: #000080 ;
}

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 0.5em;
  background-color: #fffacd;  
}

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

</style>
</head>
<body>
<div class="document" id="sympycore-user-s-guide">
<h1 class="title">SympyCore User's Guide</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Authors:</th>
<td>Pearu Peterson
<br />Fredrik Johansson</td></tr>
<tr class="field"><th class="docinfo-name">Created:</th><td class="field-body">January 2008</td>
</tr>
<tr class="field"><th class="docinfo-name">Website:</th><td class="field-body"><a class="reference" href="http://sympycore.googlecode.com/">http://sympycore.googlecode.com/</a></td>
</tr>
<tr><th class="docinfo-name">Version:</th>
<td>sympycore 0.2-svn.
Other versions: <a class="reference" href="http://sympycore.googlecode.com/svn-history/r818/trunk/doc/html/userguide.html">0.1</a>.</td></tr>
</tbody>
</table>
<!-- -*- rest -*- -->
<!-- To verify examples, use command ``python run_doctest.py`` -->
<!-- To produce HTML file, use command ``rst2html userguide.rst html/userguide.html`` -->
<!-- To produce PDF file, use command ``rst2latex userguide.rst userguide.tex; pdflatex userguide.tex`` -->
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Other formats:</th><td class="field-body"><a class="reference" href="http://sympycore.googlecode.com/svn/trunk/doc/sympycore_usersguide.pdf">PDF</a></td>
</tr>
</tbody>
</table>
<div class="sidebar">
<p class="first sidebar-title">Table of contents</p>
<div class="contents local last topic">
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id6" name="id6">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference" href="#getting-started" id="id7" name="id7">2&nbsp;&nbsp;&nbsp;Getting Started</a></li>
<li><a class="reference" href="#the-cas-model" id="id8" name="id8">3&nbsp;&nbsp;&nbsp;The CAS model</a></li>
<li><a class="reference" href="#package-structure" id="id9" name="id9">4&nbsp;&nbsp;&nbsp;Package structure</a></li>
<li><a class="reference" href="#basic-methods" id="id10" name="id10">5&nbsp;&nbsp;&nbsp;Basic methods</a><ul class="auto-toc">
<li><a class="reference" href="#output-methods" id="id11" name="id11">5.1&nbsp;&nbsp;&nbsp;Output methods</a></li>
<li><a class="reference" href="#conversation-methods" id="id12" name="id12">5.2&nbsp;&nbsp;&nbsp;Conversation methods</a></li>
<li><a class="reference" href="#substitution-of-expressions" id="id13" name="id13">5.3&nbsp;&nbsp;&nbsp;Substitution of expressions</a></li>
<li><a class="reference" href="#pattern-matching" id="id14" name="id14">5.4&nbsp;&nbsp;&nbsp;Pattern matching</a></li>
<li><a class="reference" href="#checking-for-atomic-objects" id="id15" name="id15">5.5&nbsp;&nbsp;&nbsp;Checking for atomic objects</a></li>
</ul>
</li>
<li><a class="reference" href="#verbatim-algebra" id="id16" name="id16">6&nbsp;&nbsp;&nbsp;Verbatim algebra</a></li>
<li><a class="reference" href="#commutative-ring" id="id17" name="id17">7&nbsp;&nbsp;&nbsp;Commutative ring</a><ul class="auto-toc">
<li><a class="reference" href="#operations" id="id18" name="id18">7.1&nbsp;&nbsp;&nbsp;Operations</a></li>
<li><a class="reference" href="#expanding" id="id19" name="id19">7.2&nbsp;&nbsp;&nbsp;Expanding</a></li>
<li><a class="reference" href="#differentation" id="id20" name="id20">7.3&nbsp;&nbsp;&nbsp;Differentation</a></li>
<li><a class="reference" href="#integration" id="id21" name="id21">7.4&nbsp;&nbsp;&nbsp;Integration</a></li>
</ul>
</li>
<li><a class="reference" href="#commutative-ring-implementation" id="id22" name="id22">8&nbsp;&nbsp;&nbsp;Commutative ring implementation</a><ul class="auto-toc">
<li><a class="reference" href="#defining-functions-for-collectingfield" id="id23" name="id23">8.1&nbsp;&nbsp;&nbsp;Defining functions for <tt class="docutils literal"><span class="pre">CollectingField</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#calculus" id="id24" name="id24">9&nbsp;&nbsp;&nbsp;Calculus</a></li>
<li><a class="reference" href="#arithemetics" id="id25" name="id25">10&nbsp;&nbsp;&nbsp;Arithemetics</a></li>
<li><a class="reference" href="#polynomials" id="id26" name="id26">11&nbsp;&nbsp;&nbsp;Polynomials</a><ul class="auto-toc">
<li><a class="reference" href="#univariatepolynomial" id="id27" name="id27">11.1&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt></a></li>
<li><a class="reference" href="#polynomialring" id="id28" name="id28">11.2&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">PolynomialRing</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#matrices" id="id29" name="id29">12&nbsp;&nbsp;&nbsp;Matrices</a></li>
<li><a class="reference" href="#canonical-forms-and-suppressed-evaluation" id="id30" name="id30">13&nbsp;&nbsp;&nbsp;Canonical forms and suppressed evaluation</a></li>
</ul>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id6" id="introduction" name="introduction">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
<p>The aim of the SympyCore project is to develop a robust, consistent,
and easy to extend Computer Algebra System model for Python.</p>
<p>Editorial notes:
- This document is written in <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> format.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="getting-started" name="getting-started">2&nbsp;&nbsp;&nbsp;Getting Started</a></h1>
<p>To use SympyCore from Python, one needs to import the <tt class="docutils literal"><span class="pre">sympycore</span></tt> package:</p>
<pre class="literal-block">
&gt;&gt;&gt; from sympycore import *
</pre>
<p>The <tt class="docutils literal"><span class="pre">sympycore</span></tt> package provides <tt class="docutils literal"><span class="pre">Symbol</span></tt> and <tt class="docutils literal"><span class="pre">Number</span></tt> functions to
construct symbolic objects and numbers. By default, the symbolic
objects are the elements of <tt class="docutils literal"><span class="pre">Calculus</span></tt> algebra -- a commutative
ring of symbolic expressions where exponent algebra is also <tt class="docutils literal"><span class="pre">Calculus</span></tt>
algebra.</p>
<pre class="doctest-block">
&gt;&gt;&gt; x = Symbol('x')
&gt;&gt;&gt; n = Number(2,5)
&gt;&gt;&gt; x+n
Calculus('x + 2/5')
&gt;&gt;&gt; x,y,z,v,w=map(Symbol,'xyzvw')
</pre>
<p>To construct expression from a string, use the corresponding algebra
class with one argument. For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; Calculus('x+y+1/4 + x**2')+x
Calculus('y + x**2 + 1/4 + 2*x')
</pre>
<p>More examples on <tt class="docutils literal"><span class="pre">sympycore</span></tt> features can be found in <a class="reference" href="demo0_1.html">Demo documentation</a>.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="the-cas-model" name="the-cas-model">3&nbsp;&nbsp;&nbsp;The CAS model</a></h1>
<p>Symbolic expressions represent mathematical concepts like numbers,
constants, variables, functions, operators, and various relations
between them. Symbolic objects, on the other hand, represent symbolic
expressions in a running computer program. The aim of a Computer
Algebra System (CAS) is to provide methods to manipulate symbolic
objects and by that manipulate symbolic expressions. These
manipulations of symbolic expressions have mathematical meaning when
the methods are consistent with the rules and theories from
mathematics.</p>
<p>There are many possible ways to represent a mathematical concept as a
structure of a computer program. SympyCore mimics mathematical
concepts via implementing the corresponding algebra and algebraic
operations in a class, say Algebra, that is derived from the
BasicAlgebra class. So, a symbolic object is an instance of the
Algebra class. This instance contains information about the
mathematical operator that when applied to operands forms the
corresponding symbolic object. The operator and operands of the given
symbolic object can be accessed via atrributes <tt class="docutils literal"><span class="pre">func</span></tt> and
<tt class="docutils literal"><span class="pre">args</span></tt>. The value of <tt class="docutils literal"><span class="pre">func</span></tt> is a callable object and <tt class="docutils literal"><span class="pre">args</span></tt> is a
sequence of symbolic objects. So, if <tt class="docutils literal"><span class="pre">A</span></tt> is a <tt class="docutils literal"><span class="pre">Algebra</span></tt> instance
then:</p>
<pre class="literal-block">
&lt;symbolic object&gt; = A.func(*A.args)
</pre>
<p>The actual value of <tt class="docutils literal"><span class="pre">func</span></tt> is defined by the <tt class="docutils literal"><span class="pre">Algebra</span></tt> class. For
example, in the case of calculus algebra class <tt class="docutils literal"><span class="pre">Calculus</span></tt>, the
<tt class="docutils literal"><span class="pre">func</span></tt> value can be <tt class="docutils literal"><span class="pre">Add</span></tt>, <tt class="docutils literal"><span class="pre">Mul</span></tt>, <tt class="docutils literal"><span class="pre">Pow</span></tt>, <tt class="docutils literal"><span class="pre">sin</span></tt>, <tt class="docutils literal"><span class="pre">log</span></tt>,
etc. If the symbolic object represents a symbol (eg a variable) or a
number of the algebra then <tt class="docutils literal"><span class="pre">func</span></tt> contains a callable that returns the
symbolic object (the <tt class="docutils literal"><span class="pre">args</span></tt> in this case will be an empty sequence).</p>
<p>The symbolic objects representing symbols and numbers can be
constructed via the <tt class="docutils literal"><span class="pre">Symbol</span></tt> and <tt class="docutils literal"><span class="pre">Number</span></tt> functions. Such symbolic
objects are called atomic.  One should note that functions <tt class="docutils literal"><span class="pre">Add</span></tt>,
<tt class="docutils literal"><span class="pre">Mul</span></tt>, <tt class="docutils literal"><span class="pre">Pow</span></tt>, <tt class="docutils literal"><span class="pre">Symbol</span></tt>, <tt class="docutils literal"><span class="pre">Number</span></tt>, etc are always specific to
the given algebra (in fact, they are defined as classmethods of the
corresponding algebra class).</p>
<p>While most of the algebra operators assume symbolic objects as their
operands then <tt class="docutils literal"><span class="pre">Symbol</span></tt> and <tt class="docutils literal"><span class="pre">Number</span></tt> functions may take various
Python objects as arguments. For example, the argument to
<tt class="docutils literal"><span class="pre">Calculus.Symbol</span></tt> can be any python object that is immutable (this
requirement comes from the fact terms of sums and factors of products
are internally saved as Python dictionary keys), and the arguments to
<tt class="docutils literal"><span class="pre">Calculus.Number</span></tt> can be Python number types such as <tt class="docutils literal"><span class="pre">int</span></tt>,
<tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">complex</span></tt> as well as <tt class="docutils literal"><span class="pre">mpq</span></tt>,
<tt class="docutils literal"><span class="pre">mpf</span></tt>, <tt class="docutils literal"><span class="pre">mpqc</span></tt> instances (these are defined in
<tt class="docutils literal"><span class="pre">sympycore.arithmetic</span></tt> package).</p>
<p>One can construct symbolic objects from Python strings using algebra
<tt class="docutils literal"><span class="pre">convert</span></tt> class method or algebra constructor with one argument. For
example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; Calculus.convert('a-3/4+b**2')
Calculus('a + b**2 - 3/4')
&gt;&gt;&gt; Calculus('a-3/4+b**2').func
&lt;bound method type.Add of &lt;class 'sympycore.calculus.algebra.Calculus'&gt;&gt;
&gt;&gt;&gt; Calculus('a-3/4+b**2').args
[Calculus('a'), Calculus('-3/4'), Calculus('b**2')]
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id9" id="package-structure" name="package-structure">4&nbsp;&nbsp;&nbsp;Package structure</a></h1>
<p>SympyCore project provides a python package <tt class="docutils literal"><span class="pre">sympycore</span></tt> that consists of
several modules and subpackages:</p>
<ol class="arabic">
<li><p class="first"><tt class="docutils literal"><span class="pre">core.py</span></tt> - provides a base class <tt class="docutils literal"><span class="pre">Basic</span></tt> to all symbolic
objects. Note that almost any (hashable) python object can be used
as an operand to algebraic operations (assuming the corresponding
algebra class accepts it) and hence it is not always necessary to
derive classes defining some mathematical notion from
<tt class="docutils literal"><span class="pre">Basic</span></tt>. Only classes that could be used by other parts of the
<tt class="docutils literal"><span class="pre">sympycore</span></tt> should be derived from <tt class="docutils literal"><span class="pre">Basic</span></tt>. In such cases,
these classes are available via <tt class="docutils literal"><span class="pre">classes</span></tt> attributes (also
defined in <tt class="docutils literal"><span class="pre">core.py</span></tt>). For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; from sympycore.core import classes
&gt;&gt;&gt; classes.Calculus
&lt;class 'sympycore.calculus.algebra.Calculus'&gt;
&gt;&gt;&gt; classes.Unit
&lt;class 'sympycore.physics.units.Unit'&gt;
&gt;&gt;&gt; classes.CollectingField
&lt;class 'sympycore.basealgebra.pairs.CollectingField'&gt;
</pre>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">arithmetic/</span></tt> - provides <tt class="docutils literal"><span class="pre">mpq</span></tt>, <tt class="docutils literal"><span class="pre">mpf</span></tt>, <tt class="docutils literal"><span class="pre">mpqc</span></tt>,
<tt class="docutils literal"><span class="pre">mpc</span></tt> classes that represent low-level fractions,
multiprecision floating point numbers, and complex numbers with
rational parts. The package defines also <tt class="docutils literal"><span class="pre">Infinity</span></tt> class to
represent extended numbers.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">basealgebra/</span></tt> - provides abstract base classes representing
algebras: <tt class="docutils literal"><span class="pre">BasicAlgebra</span></tt>, <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>, etc, and base
classes for algebras with implementations: <tt class="docutils literal"><span class="pre">Primitive</span></tt>,
<tt class="docutils literal"><span class="pre">CollectingField</span></tt>, etc.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">calculus/</span></tt> - provides class <tt class="docutils literal"><span class="pre">Calculus</span></tt> that represents the
algebra of symbolic expressions. The <tt class="docutils literal"><span class="pre">Calculus</span></tt> class defines the
default algebra in <tt class="docutils literal"><span class="pre">sympycore</span></tt>. For more information, see
[section on calculus].  <tt class="docutils literal"><span class="pre">calculus/functions/</span></tt> - provides symbolic
functions like <tt class="docutils literal"><span class="pre">exp</span></tt>, <tt class="docutils literal"><span class="pre">log</span></tt>, <tt class="docutils literal"><span class="pre">sin</span></tt>, <tt class="docutils literal"><span class="pre">cos</span></tt>, <tt class="docutils literal"><span class="pre">tan</span></tt>,
<tt class="docutils literal"><span class="pre">cot</span></tt>, <tt class="docutils literal"><span class="pre">sqrt</span></tt>, ...</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">physics/</span></tt> - provides class <tt class="docutils literal"><span class="pre">Unit</span></tt> that represents the algebra
of symbolic expressions of physical quantities. For more
information, see [section on physics].</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">polynomials/</span></tt> - provides classes <tt class="docutils literal"><span class="pre">Polynomial</span></tt>,
<tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt>, <tt class="docutils literal"><span class="pre">MultivariatePolynomial</span></tt> to represent
the algebras of polynomials with symbols, univariate polynomials in
(coefficient:exponent) form, and multivariate polynomials in
(coefficients:exponents) form, respectively. For more information,
see [section on polynomials].</p>
</li>
</ol>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id10" id="basic-methods" name="basic-methods">5&nbsp;&nbsp;&nbsp;Basic methods</a></h1>
<p>In <tt class="docutils literal"><span class="pre">sympycore</span></tt> all symbolic objects are assumed to be immutable. So,
the manipulation of symbolic objects means creating new symbolic
objects from the parts of existing ones.</p>
<p>There are many methods that can be used to retrive information and
subexpressions from a symbolic object. The most generic method is to
use attribute pair of <tt class="docutils literal"><span class="pre">func</span></tt> and <tt class="docutils literal"><span class="pre">args</span></tt> as described
above. However, many such methods are also algebra specific, for
example, classes of commutative rings have methods like
<tt class="docutils literal"><span class="pre">as_Add_args</span></tt>, <tt class="docutils literal"><span class="pre">as_Mul_args</span></tt>, etc for retriving the operands of
operations and <tt class="docutils literal"><span class="pre">Add</span></tt>, <tt class="docutils literal"><span class="pre">Mul</span></tt>, etc for constructing new symbolic
objects representing addition, multiplication, etc operations. For
more information about such methods, see sections describing the
particular algebra classes.</p>
<div class="section">
<h2><a class="toc-backref" href="#id11" id="output-methods" name="output-methods">5.1&nbsp;&nbsp;&nbsp;Output methods</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">str(&lt;symbolic</span> <span class="pre">object&gt;)</span></tt></dt>
<dd><p class="first">return a nice string representation of the symbolic object. For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr = Calculus('-x + 2')
&gt;&gt;&gt; str(expr)
'2 - x'
</pre>
</dd>
<dt><tt class="docutils literal"><span class="pre">repr(&lt;symbolic</span> <span class="pre">object&gt;)</span></tt></dt>
<dd><p class="first">return a string representation of the symbolic object that can be
used to reproduce an equal object:</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr=Calculus('-x+2')
&gt;&gt;&gt; repr(expr)
&quot;Calculus('2 - x')&quot;
</pre>
</dd>
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.as_tree()</span></tt></dt>
<dd><p class="first">return a tree string representation of the symbolic object. For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; expr = Calculus('-x + 2+y**3')
&gt;&gt;&gt; print expr.as_tree()
Calculus:
ADD[
  -1:SYMBOL[x]
  1:MUL[
  1:  3:SYMBOL[y]
  1:]
  2:NUMBER[1]
]
</pre>
<p class="last">where the first line shows the name of a algebra class following the
content of the symbolic object in tree form. Note how are
represented the coefficients and exponents of the example
subexpressions.</p>
</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id12" id="conversation-methods" name="conversation-methods">5.2&nbsp;&nbsp;&nbsp;Conversation methods</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.as_verbatim()</span></tt></dt>
<dd><p class="first">return symbolic object as an instance of <tt class="docutils literal"><span class="pre">Verbatim</span></tt> class. All
algebra classes must implement <tt class="docutils literal"><span class="pre">as_verbatim</span></tt> method as this allows
converting symbolic objects from one algebra to another that is
compatible with respect to algebraic operations. Also, producing the
string representations of symbolic objects is done via converting
them to Verbatim that implements the corresponding printing
method. For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr
Calculus('2 + y**3 - x')
&gt;&gt;&gt; expr.as_verbatim()
Verbatim('2 + y**3 - x')
</pre>
</dd>
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.as_algebra(&lt;algebra</span> <span class="pre">class&gt;)</span></tt></dt>
<dd><p class="first">return symbolic object as an instance of given algebra class. The
transformation is done by first converting the symbolic object to
<tt class="docutils literal"><span class="pre">Verbatim</span></tt> instance which in turn is converted to the instance
of targer algebra class by executing the corresponding target
algebra operators on operands. For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr = Calculus('-x + 2')
&gt;&gt;&gt; print expr.as_tree()
Calculus:
ADD[
  -1:SYMBOL[x]
  2:NUMBER[1]
]
&gt;&gt;&gt; print expr.as_algebra(Verbatim).as_tree()
Verbatim:
ADD[
  NEG[
    SYMBOL[x]
  ]
  NUMBER[2]
]
&gt;&gt;&gt; print expr.as_algebra(CollectingField).as_tree()
CollectingField:
ADD[
  -1:SYMBOL[x]
  2:NUMBER[1]
]
</pre>
</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id13" id="substitution-of-expressions" name="substitution-of-expressions">5.3&nbsp;&nbsp;&nbsp;Substitution of expressions</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.subs(&lt;sub-expr&gt;,</span> <span class="pre">&lt;new-expr&gt;)</span></tt></dt>
<dd><p class="first">return a copy of <tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;</span></tt> with all occurances of
<tt class="docutils literal"><span class="pre">&lt;sub-expr&gt;</span></tt> replaced with <tt class="docutils literal"><span class="pre">&lt;new-expr&gt;</span></tt>. For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr = Calculus('-x + 2+y**3')
&gt;&gt;&gt; expr
Calculus('2 + y**3 - x')
&gt;&gt;&gt; expr.subs('y', '2*z')
Calculus('2 + 8*z**3 - x')
</pre>
</dd>
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.subs([(&lt;subexpr1&gt;,</span> <span class="pre">&lt;newexpr1&gt;),</span> <span class="pre">(&lt;subexpr2&gt;,</span> <span class="pre">&lt;newexpr2&gt;),</span> <span class="pre">...])</span></tt></dt>
<dd><p class="first">is equivalent to <tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.subs(&lt;subexp1&gt;,</span>
<span class="pre">&lt;newexpr1&gt;).subs(&lt;subexpr2&gt;,</span> <span class="pre">&lt;newexpr2&gt;).subs</span></tt>. For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr
Calculus('2 + y**3 - x')
&gt;&gt;&gt; expr.subs([('y', '2*z'),('z', 2)])
Calculus('66 - x')
</pre>
</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id14" id="pattern-matching" name="pattern-matching">5.4&nbsp;&nbsp;&nbsp;Pattern matching</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.match(&lt;pattern-expr&gt;</span> <span class="pre">[,</span> <span class="pre">&lt;wildcard1&gt;,</span> <span class="pre">&lt;wildcard2&gt;</span> <span class="pre">...])</span></tt></dt>
<dd><p class="first">check if the give symbolic object matches given pattern. Pattern
expression may contain wild symbols that match arbitrary
expressions, the <tt class="docutils literal"><span class="pre">wildcard</span></tt> must be then the corresponding
symbol. Wild symbols can be matched also conditionally, then the
<tt class="docutils literal"><span class="pre">&lt;wildcard&gt;</span></tt> argument must be a tuple <tt class="docutils literal"><span class="pre">(&lt;wild-symbol&gt;,</span> <span class="pre">&lt;predicate&gt;)</span></tt>,
where <tt class="docutils literal"><span class="pre">&lt;predicate&gt;</span></tt> is a single-argument function returning <tt class="docutils literal"><span class="pre">True</span></tt> if
wild symbol matches the expression in argument. If the match is not
found then the method returns. Otherwise it will return a dictionary
object such that the following condition holds:</p>
<pre class="literal-block">
pattern.subs(expr.match(pattern, ...).items()) == expr
</pre>
<p>For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr = 3*x + 4*y
&gt;&gt;&gt; pattern = v*x + w*y
&gt;&gt;&gt; d = expr.match(pattern, v, w)
&gt;&gt;&gt; print 'v=',d.get(v)
v= 3
&gt;&gt;&gt; print 'w=',d.get(w)
w= 4
&gt;&gt;&gt; pattern.subs(d.items())==expr
True
</pre>
</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id15" id="checking-for-atomic-objects" name="checking-for-atomic-objects">5.5&nbsp;&nbsp;&nbsp;Checking for atomic objects</a></h2>
<p>A symbolic object is atomic if <tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.args</span> <span class="pre">==</span> <span class="pre">()</span></tt>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.symbols</span></tt></dt>
<dd>is a property that holds a set of all atomic symbols in the given
symbolic expression.</dd>
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.has(&lt;symbol&gt;)</span></tt></dt>
<dd>returns <tt class="docutils literal"><span class="pre">True</span></tt> if the symbolic expression contains <tt class="docutils literal"><span class="pre">&lt;symbol&gt;</span></tt>.</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id16" id="verbatim-algebra" name="verbatim-algebra">6&nbsp;&nbsp;&nbsp;Verbatim algebra</a></h1>
<p>Verbatim algebra elements are symbolic expressions that are not
simplified in anyway when performing operatons. For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; s=Verbatim('s')
&gt;&gt;&gt; s+s
Verbatim('s + s')
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id17" id="commutative-ring" name="commutative-ring">7&nbsp;&nbsp;&nbsp;Commutative ring</a></h1>
<p>In SympyCore a commutative ring is represented by an abstract class
<tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>.  The <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt> class defines support
for addition, substraction, multiplication, division, and
exponentiation operations.</p>
<div class="section">
<h2><a class="toc-backref" href="#id18" id="operations" name="operations">7.1&nbsp;&nbsp;&nbsp;Operations</a></h2>
<p>Classes deriving from <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt> must define a number of
method pairs <tt class="docutils literal"><span class="pre">(Operation,</span> <span class="pre">as_Operation_args)</span></tt> that satisfy the
following condition:</p>
<pre class="literal-block">
cls.Operation(*obj.as_Operation_args()) == obj
</pre>
<p>Here <tt class="docutils literal"><span class="pre">Operation</span></tt> can be <tt class="docutils literal"><span class="pre">Add</span></tt>, <tt class="docutils literal"><span class="pre">Mul</span></tt>, <tt class="docutils literal"><span class="pre">Terms</span></tt>, <tt class="docutils literal"><span class="pre">Factors</span></tt>,
<tt class="docutils literal"><span class="pre">Pow</span></tt>, <tt class="docutils literal"><span class="pre">Log</span></tt>. For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; print map(str, (2*x+y).as_Add_args())
['y', '2*x']
&gt;&gt;&gt; print map(str, (2*x+y).as_Mul_args())
['y + 2*x']
&gt;&gt;&gt; print map(str, (2*x+y).as_Pow_args())
['y + 2*x', '1']
&gt;&gt;&gt; print (2*x+y).as_Terms_args()
[(Calculus('y'), 1), (Calculus('x'), 2)]
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id19" id="expanding" name="expanding">7.2&nbsp;&nbsp;&nbsp;Expanding</a></h2>
<p>Expanding means applying distributivity law to open parenthesis.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.expand()</span></tt></dt>
<dd><p class="first">return an expanded expression. For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; expr = x*(y+x)**2
&gt;&gt;&gt; print expr
x*(x + y)**2
&gt;&gt;&gt; print expr.expand()
x**3 + 2*y*x**2 + x*y**2
</pre>
</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id20" id="differentation" name="differentation">7.3&nbsp;&nbsp;&nbsp;Differentation</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.diff(*symbols)</span></tt></dt>
<dd><p class="first">return a derivative of symbolic expression with respect to given
symbols. The diff methods argument can also be a positive integer
after some symbol argument. Then the derivative is computed given
number of times with respect to the last symbol.
For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; print sin(x*y).diff(x)
y*cos(x*y)
&gt;&gt;&gt; print sin(x*y).diff(x).diff(y)
cos(x*y) - x*y*sin(x*y)
&gt;&gt;&gt; print sin(x*y).diff(x,4)
sin(x*y)*y**4
</pre>
</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id21" id="integration" name="integration">7.4&nbsp;&nbsp;&nbsp;Integration</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.integrate(&lt;symbol&gt;,</span> <span class="pre">integrator=None)</span></tt></dt>
<dd><p class="first">return an antiderivative of a symbolic expression with respect to
<tt class="docutils literal"><span class="pre">&lt;symbol&gt;</span></tt>.
For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; from sympycore import *
&gt;&gt;&gt; print (x**2 + x*y).integrate(x)
1/2*y*x**2 + 1/3*x**3
</pre>
</dd>
<dt><tt class="docutils literal"><span class="pre">&lt;symbolic</span> <span class="pre">object&gt;.integrate((&lt;symbol&gt;,</span> <span class="pre">&lt;a&gt;,</span> <span class="pre">&lt;b&gt;)</span></tt></dt>
<dd><p class="first">return a defined integral of a symbolic expression with respect to
<tt class="docutils literal"><span class="pre">&lt;symbol&gt;</span></tt> over the interval <tt class="docutils literal"><span class="pre">[&lt;a&gt;,</span> <span class="pre">&lt;b&gt;]</span></tt>.
For example,</p>
<pre class="last doctest-block">
&gt;&gt;&gt; from sympycore import *
&gt;&gt;&gt; print (x**2 + x*y).integrate(x)
1/2*y*x**2 + 1/3*x**3
&gt;&gt;&gt; print (x**2 + x*y).integrate((x, 1, 3))
26/3 + 4*y
</pre>
</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id22" id="commutative-ring-implementation" name="commutative-ring-implementation">8&nbsp;&nbsp;&nbsp;Commutative ring implementation</a></h1>
<p>Commutative ring operations are implemented in the class
<tt class="docutils literal"><span class="pre">CollectingField</span></tt> (derived from <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>).</p>
<p>The class <tt class="docutils literal"><span class="pre">CollectingField</span></tt> holds two attributes, <tt class="docutils literal"><span class="pre">head</span></tt>
and <tt class="docutils literal"><span class="pre">data</span></tt>. The attribute <tt class="docutils literal"><span class="pre">head</span></tt> defines the meaning of the
attribute <tt class="docutils literal"><span class="pre">data</span></tt> content:</p>
<ol class="arabic simple">
<li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==SYMBOL</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is treated as an element
of the ring. Usually <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is a Python string object but
in general it can be any hashable Python object.</li>
<li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==NUMBER</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is treated as a
number element of the ring, that is, an element that can be
represented as <em>one * n</em> where <em>one</em> is unit element of the ring
and <em>n</em> is a number saved in <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt>. Usually <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt>
is a Python <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">complex</span></tt> object but it
can be also any other number-like object that supports arithmetic
operations with Python numbers. An examples are <tt class="docutils literal"><span class="pre">mpq</span></tt>,
<tt class="docutils literal"><span class="pre">mpf</span></tt>, <tt class="docutils literal"><span class="pre">mpqc</span></tt> classes defined in <tt class="docutils literal"><span class="pre">sympycore.arithmetic</span></tt>
package.</li>
<li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==TERMS</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> contains a Python
dictionary holding the pairs <tt class="docutils literal"><span class="pre">(&lt;ring</span> <span class="pre">element&gt;,</span> <span class="pre">&lt;coefficient&gt;)</span></tt>.
The values of <tt class="docutils literal"><span class="pre">&lt;coefficients&gt;</span></tt> can be Python numbers or
number-like objects or elements of some other ring (for example,
see <tt class="docutils literal"><span class="pre">Unit</span></tt> class where the coefficients are <tt class="docutils literal"><span class="pre">Calculus</span></tt>
instances). For example, if <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> is <tt class="docutils literal"><span class="pre">{x:2,</span> <span class="pre">y:1}</span></tt> then
<tt class="docutils literal"><span class="pre">&lt;obj&gt;</span></tt> represents an expression <em>y + 2*x</em>.</li>
<li>If <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head==FACTORS</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> contains a Python
dictionary holding the pairs <tt class="docutils literal"><span class="pre">(&lt;ring</span> <span class="pre">element&gt;,</span> <span class="pre">&lt;exponent&gt;)</span></tt>.  The
values of <tt class="docutils literal"><span class="pre">&lt;coefficients&gt;</span></tt> can be Python numbers of number-like
objects or elements of some ring (for exapmle, see <tt class="docutils literal"><span class="pre">Calculus</span></tt>
class where the exponents can also be <tt class="docutils literal"><span class="pre">Calculus</span></tt> instances).</li>
<li>If <tt class="docutils literal"><span class="pre">callable(&lt;obj&gt;.head)</span></tt> then <tt class="docutils literal"><span class="pre">&lt;obj&gt;</span></tt> represents an applied
function where <tt class="docutils literal"><span class="pre">&lt;obj&gt;.head</span></tt> contains a callable object that
performs evaluation and <tt class="docutils literal"><span class="pre">&lt;obj&gt;.data</span></tt> contains an argument
instance (for example, an instance of some algebra elements)
or a Python <tt class="docutils literal"><span class="pre">tuple</span></tt> containing argument instances.</li>
</ol>
<p>The constants <tt class="docutils literal"><span class="pre">SYMBOL</span></tt>, <tt class="docutils literal"><span class="pre">NUMBER</span></tt>, <tt class="docutils literal"><span class="pre">TERMS</span></tt>, <tt class="docutils literal"><span class="pre">FACTORS</span></tt> are defined
in <tt class="docutils literal"><span class="pre">sympycore/utils.py</span></tt>.</p>
<p>For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; from sympycore.utils import head_to_string
&gt;&gt;&gt; head_to_string[x.head]
'SYMBOL'
&gt;&gt;&gt; x.data
'x'
&gt;&gt;&gt; head_to_string[(x+y).head]
'ADD'
&gt;&gt;&gt; (x+y).data == {x:1,y:1}
True
&gt;&gt;&gt; head_to_string[(x**y).head]
'MUL'
&gt;&gt;&gt; (x**y).data
{Calculus('x'): Calculus('y')}
&gt;&gt;&gt; sin(x).head
&lt;class 'sympycore.calculus.functions.elementary.sin'&gt;
&gt;&gt;&gt; sin(x).data
Calculus('x')
</pre>
<div class="section">
<h2><a class="toc-backref" href="#id23" id="defining-functions-for-collectingfield" name="defining-functions-for-collectingfield">8.1&nbsp;&nbsp;&nbsp;Defining functions for <tt class="docutils literal"><span class="pre">CollectingField</span></tt></a></h2>
<p>The representation of an applied function within the class
<tt class="docutils literal"><span class="pre">CollectingField</span></tt> can hold any Python callable object that
satisfies the following basic condition: it must return an instance of
a algebra class. The instance may represent an evaluated result of
applying the function to its arguments, or when evaluation is not
possible, then it return <tt class="docutils literal"><span class="pre">&lt;algebra</span> <span class="pre">class&gt;(&lt;arguments&gt;,</span>
<span class="pre">head=&lt;callable&gt;)</span></tt>.</p>
<p>For example, let us define a customized sinus function:</p>
<pre class="doctest-block">
&gt;&gt;&gt; def mysin(x):
...     if x==0:
...         return x
...     return Calculus(mysin, x)
...
&gt;&gt;&gt; mysin(0)
0
&gt;&gt;&gt; print mysin(x+y)
mysin(x + y)
</pre>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id24" id="calculus" name="calculus">9&nbsp;&nbsp;&nbsp;Calculus</a></h1>
<p>The default algebra of symbolic expressions with commutative ring
operations is represented by the <tt class="docutils literal"><span class="pre">Calculus</span></tt> class (derived from
<tt class="docutils literal"><span class="pre">CollectingField</span></tt>). The <tt class="docutils literal"><span class="pre">Calculus</span></tt> class can handle
rational numbers represented by the <tt class="docutils literal"><span class="pre">mpq</span></tt> class, multi-precision
floating point numbers represented by the <tt class="docutils literal"><span class="pre">mpf</span></tt> class, and
rational complex numbers represented by the <tt class="docutils literal"><span class="pre">mpqc</span></tt> class.</p>
<p>The <tt class="docutils literal"><span class="pre">sympycore.calculus.functions</span></tt> package defines the following
symbolic functions: <tt class="docutils literal"><span class="pre">sqrt</span></tt>, <tt class="docutils literal"><span class="pre">exp</span></tt>, <tt class="docutils literal"><span class="pre">log</span></tt>, <tt class="docutils literal"><span class="pre">sin</span></tt>, <tt class="docutils literal"><span class="pre">cos</span></tt>,
<tt class="docutils literal"><span class="pre">tan</span></tt>, <tt class="docutils literal"><span class="pre">cot</span></tt>. It also provides <tt class="docutils literal"><span class="pre">Calculus</span></tt> based interfaces to
constants <tt class="docutils literal"><span class="pre">E</span></tt>, <tt class="docutils literal"><span class="pre">pi</span></tt>, and symbols <tt class="docutils literal"><span class="pre">I</span></tt>, <tt class="docutils literal"><span class="pre">oo</span></tt>, <tt class="docutils literal"><span class="pre">moo</span></tt>, <tt class="docutils literal"><span class="pre">zoo</span></tt>,
<tt class="docutils literal"><span class="pre">undefined</span></tt>.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id25" id="arithemetics" name="arithemetics">10&nbsp;&nbsp;&nbsp;Arithemetics</a></h1>
<p>The <tt class="docutils literal"><span class="pre">sympycore.arithmetic</span></tt> package is not an algebra package but it
implements fractions, multi-precision floating point numbers, rational
complex numbers, and <a class="reference" href="evaluation_rules.html#extended-numbers">extended numbers</a>. In addition, it implements
various algorithms from number theory and provides methods to compute
the values of constants like pi and Eulers number, etc.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id26" id="polynomials" name="polynomials">11&nbsp;&nbsp;&nbsp;Polynomials</a></h1>
<p>The <tt class="docutils literal"><span class="pre">sympycore.polynomials</span></tt> package has two different
implementations for polynomials: <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> and
<tt class="docutils literal"><span class="pre">PolynomialRing</span></tt>.</p>
<div class="section">
<h2><a class="toc-backref" href="#id27" id="univariatepolynomial" name="univariatepolynomial">11.1&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt></a></h2>
<p>The <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> class stores polynomial coefficients in a
Python tuple. The exponents are implicitly defined as indices of the
list so that the degree of a polynomial is equal to the length of the
list minus 1. <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> is most efficient for
manipulating low order and dense polynomials. To specify the variable
symbol of a polynomial, use <tt class="docutils literal"><span class="pre">symbol</span></tt> keyword argument (default
variable symbol is <tt class="docutils literal"><span class="pre">x</span></tt>).</p>
<pre class="doctest-block">
&gt;&gt;&gt; poly([4,3,2,1])
4 + 3*x + 2*x**2 + x**3
&gt;&gt;&gt; poly([4,3,2,1]).degree
3
&gt;&gt;&gt; poly([4,3,2,1],symbol='y')
4 + 3*y + 2*y**2 + y**3
</pre>
<p>Coefficients can be arbitrary symbolic expressions:</p>
<pre class="doctest-block">
&gt;&gt;&gt; poly([2,y+1,y+z])
2 + ((1 + y))*x + ((y + z))*x**2
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id28" id="polynomialring" name="polynomialring">11.2&nbsp;&nbsp;&nbsp;<tt class="docutils literal"><span class="pre">PolynomialRing</span></tt></a></h2>
<p>The <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> based classes store polynomial exponenets and
coefficients information in a Python dictionary object where keys are
exponenents (in univariate case Python integers, in multivariate case
<tt class="docutils literal"><span class="pre">AdditiveTuple</span></tt> instances) and values are coefficients.
<tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> is most efficient for manipulating sparse
polynomials.  The coefficients belong to specified ring (default ring
is <tt class="docutils literal"><span class="pre">Calculus</span></tt>).</p>
<p>The <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> class (derived from <tt class="docutils literal"><span class="pre">CommutativeRing</span></tt>) is
a base class to various polynomial rings with different coefficent
rings and different number of variables. To create a class
representing a polynomial element with variables <tt class="docutils literal"><span class="pre">(X,</span> <span class="pre">Y,</span> <span class="pre">..)</span></tt> and
with <tt class="docutils literal"><span class="pre">&lt;ring&gt;</span></tt> coefficients, use one of the following constructions:</p>
<pre class="literal-block">
PolynomialRing[(X, Y, ..), &lt;ring&gt;]
PolynomialRing[&lt;int&gt;, &lt;ring&gt;]
</pre>
<p>where nonnegative <tt class="docutils literal"><span class="pre">&lt;int&gt;</span></tt> specifies the number of variables (default
symbols are then <tt class="docutils literal"><span class="pre">X0</span></tt>, <tt class="docutils literal"><span class="pre">X1</span></tt>, etc). The <tt class="docutils literal"><span class="pre">&lt;ring&gt;</span></tt> argument can be
omitted, then <tt class="docutils literal"><span class="pre">Calculus</span></tt> is used as a default ring.  Variables can
be arbitrary symbolic expressions.</p>
<p>For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; polyXY = PolynomialRing[('X', 'Y'), Calculus]
&gt;&gt;&gt; polyXY
&lt;class 'sympycore.polynomials.algebra.PolynomialRing[(X, Y), Calculus]'&gt;
</pre>
<p>To create a polynomial with given exponents and coefficients pairs,
the <tt class="docutils literal"><span class="pre">PolynomialRing</span></tt> constructor accepts dictinary objects
containing the corresponding pairs:</p>
<pre class="doctest-block">
&gt;&gt;&gt; polyXY.convert({(0,0):4, (2,1):3, (0,3):2})
PolynomialRing[(X, Y), Calculus]('3*X**2*Y + 2*Y**3 + 4')
</pre>
<p>Univariate polynomials can also be constructed from a list in the same
way as <tt class="docutils literal"><span class="pre">UnivariatePolynomial</span></tt> instances were constructed above:</p>
<pre class="doctest-block">
&gt;&gt;&gt; PolynomialRing[1].convert([4,3,2,1])
PolynomialRing[X0, Calculus]('X0**3 + 2*X0**2 + 3*X0 + 4')
</pre>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id29" id="matrices" name="matrices">12&nbsp;&nbsp;&nbsp;Matrices</a></h1>
<p>The <tt class="docutils literal"><span class="pre">sympycore.matrices</span></tt> package defines <tt class="docutils literal"><span class="pre">MatrixRing</span></tt> that is base
class to matrix algebras. Matrix algebras are represented as classes
(derived from <tt class="docutils literal"><span class="pre">MatrixRing</span></tt>) parametrized with matrix shape and
element ring (default ring is <tt class="docutils literal"><span class="pre">Calculus</span></tt>). To create a matrix
ring, use the following constructs:</p>
<pre class="literal-block">
MatrixRing[&lt;shape&gt;, &lt;ring&gt;]
SquareMatrix[&lt;size&gt;, &lt;ring&gt;]
PermutationMatrix[&lt;size&gt;]
</pre>
<p>where <tt class="docutils literal"><span class="pre">&lt;ring&gt;</span></tt> can be omitted, then <tt class="docutils literal"><span class="pre">Calculus</span></tt> is used as a
default element ring.</p>
<p>For example,</p>
<pre class="doctest-block">
&gt;&gt;&gt; m=MatrixRing[3,4]({})
&gt;&gt;&gt; print m
 0  0  0  0
 0  0  0  0
 0  0  0  0
&gt;&gt;&gt; m[1,2] = 3
&gt;&gt;&gt; m[2,3] = 4
&gt;&gt;&gt; print m
 0  0  0  0
 0  0  3  0
 0  0  0  4
</pre>
<p>The content of the matrix is stored as a dictionary containing
pairs <tt class="docutils literal"><span class="pre">(&lt;rowindex&gt;,&lt;column-index&gt;):</span> <span class="pre">&lt;non-zero</span> <span class="pre">element&gt;</span></tt>.</p>
<p>Matrix instances can be constructed from Python dictionary or from a
Python list:</p>
<pre class="doctest-block">
&gt;&gt;&gt; print MatrixRing[2,2]({(0,0):1,(0,1):2,(1,1):3})
 1  2
 0  3
&gt;&gt;&gt; print MatrixRing[2,2]([[1,2],[3,4]])
 1  2
 3  4
</pre>
<p>Permutation matrices can be constructed from a sequence of
integers:</p>
<pre class="doctest-block">
&gt;&gt;&gt; print PermutationMatrix([1,0,2])
 0  1  0
 1  0  0
 0  0  1
</pre>
<p>Use <tt class="docutils literal"><span class="pre">random()</span></tt> classmethod to construct matrices with random
content:</p>
<pre class="doctest-block">
&gt;&gt;&gt; print SquareMatrix[2].random()         #doctest: +SKIP
 -1  3
  3  0
&gt;&gt;&gt; print SquareMatrix[2].random((10,20))  #doctest: +SKIP
 15  10
 13  15
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id30" id="canonical-forms-and-suppressed-evaluation" name="canonical-forms-and-suppressed-evaluation">13&nbsp;&nbsp;&nbsp;Canonical forms and suppressed evaluation</a></h1>
<p>See also <a class="reference" href="evaluation_rules.html">Automatic evaluation rules of symbolic expressions</a>.</p>
<p>The <tt class="docutils literal"><span class="pre">Calculus</span></tt> algebra automatically applies some transformations to
expressions. The purpose of these transformations is to permit quick
recognition of mathematically equivalent expressions.
Sums and products of numbers are always evaluated, and
multiples/powers of identical subexpressions are automatically
collected together.  Rational factors are also automatically
distributed over sums. For example, the following transformations
are performed automatically:</p>
<pre class="literal-block">
2*3 -&gt; 6

x+x -&gt; 2*x

x*x -&gt; x**2

2*(x+y) -&gt; 2*x + 2*y
</pre>
<p>An expression to which default transformations have been applied is
said to be in canonical or normalized form. The enforcement of
canonical forms is important for performance reasons as it ensures that,
in many important basic cases, expressions that are mathematically
equivalent will be recognized directly as equal no matter in what
form they were entered, without the need to apply additional
transformations. The default transformations described above
ensure that for example the following expressions cancel completely:</p>
<pre class="literal-block">
2*3 - 6 -&gt; 0

x+x - (2*x) -&gt; 0

x*x - x**2 -&gt; 0

2*(x-y) + 2*(y-x) -&gt; 0
</pre>
<p>Ideally we would like the canonical form to be the simplest
expression possible, e.g.:</p>
<pre class="literal-block">
cos(x)**2 + sin(x)**2 -&gt; 1
</pre>
<p>Automatically generating the simplest possible form is not always
possible, as some expressions have multiple valid representations that
may each be useful in different contexts. E.g.: <tt class="docutils literal"><span class="pre">cos(2*x)</span></tt> and
<tt class="docutils literal"><span class="pre">cos(x)**2</span> <span class="pre">-</span> <span class="pre">sin(x)**2</span></tt>. In general, detecting whether two expressions are
equal is not even algorithmically decidable, and even when it is
possible, the required simplifications can be extremely computationally
expensive (and unpredictably so).</p>
<p>Default transformations are limited to performing operations cases that
are fast and have predictable behavior. To perform more expensive
simplifications, one should explicitly invoke <tt class="docutils literal"><span class="pre">simplify()</span></tt> or, depending on
the desired form, special-purpose rewriting functions like <tt class="docutils literal"><span class="pre">collect()</span></tt>,
<tt class="docutils literal"><span class="pre">apart()</span></tt>, etc (note: these are not yet implemented in SympyCore).</p>
<p>It can sometimes be useful to bypass automatic transformations, for
example to keep the expression <tt class="docutils literal"><span class="pre">2*(x+y)</span></tt> in factored form. The most
general way to achieve this is to use the <tt class="docutils literal"><span class="pre">Verbatim</span></tt> class
(which performs no simplifications whatsoever) instead of <tt class="docutils literal"><span class="pre">Calculus</span></tt>.</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; Verbatim('2*(x+pi)')
Verbatim('2*(x + pi)')
</pre>
</blockquote>
<p>You can also construct non-canonical <tt class="docutils literal"><span class="pre">Calculus</span></tt> instances by manually
passing data to the <tt class="docutils literal"><span class="pre">Calculus</span></tt> constructor. For example:</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; p = Calculus(utils.TERMS, {(pi+x):2})
&gt;&gt;&gt; print p
2*(pi + x)
</pre>
</blockquote>
<p>It is important to note that some <tt class="docutils literal"><span class="pre">Calculus</span></tt> functions assume the input to
be in canonical form. Although they should never break (i.e. generate
invalid results) when given noncanonical input, they may fail to simplify
results. For example, <tt class="docutils literal"><span class="pre">sin</span></tt> assumes its argument to be flattened such that
if it contains an integer multiple of pi that can be eliminated, this term
will be available at the top of the expression. Thus:</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; sin(2*(pi+x))  # sin(2*pi + 2*x)
Calculus('sin(2*x)')
&gt;&gt;&gt; sin(p)
Calculus('sin(2*(pi + x))')
</pre>
</blockquote>
<p>To canonize an expression, either use the function XXX or convert it to
<tt class="docutils literal"><span class="pre">Verbatim</span></tt> and then back to <tt class="docutils literal"><span class="pre">Calculus</span></tt>.</p>
<blockquote>
<pre class="doctest-block">
&gt;&gt;&gt; Calculus(Verbatim(p))
Calculus('2*pi + 2*x')
</pre>
</blockquote>
</div>
</div>
</body>
</html>
